chore(track-performance): local iteration #1642

Elvis339 · 2026-01-26T18:06:18Z

Add local developer tooling for triggering C-Chain reexecution benchmarks. Includes just recipe, gh CLI in nix devshell, and usage documentation in METRICS.md.

Note: should be merged after #1493

Why this should be merged

Enables developers to trigger C-Chain reexecution benchmarks from their local environment without navigating GitHub Actions UI. This complements the track-performance.yml workflow by providing a CLI interface.

How this works

The bench-cchain recipe:

Validates inputs (predefined test name OR custom block params)
Triggers track-performance.yml via gh workflow run
Polls for workflow registration (handles GitHub's async dispatch)
Watches the run until completion

Environment variables support custom configurations:

FIREWOOD_REF - specific commit/tag to benchmark
AVALANCHEGO_REF - AvalancheGo version to test against
START_BLOCK, END_BLOCK, BLOCK_DIR_SRC - custom block ranges

How this was tested

nix run ./ffi#gh -- gh auth login

GH_TOKEN=$(gh auth token) RUNNER=avalanche-avalanchego-runner-2ti FIREWOOD_REF=v0.0.18 CONFIG=firewood START_BLOCK=1 END_BLOCK=100 BLOCK_DIR_SRC=cchain-mainnet-blocks-200-ldb just bench-cchain

Add local developer tooling for triggering C-Chain reexecution benchmarks. Includes just recipe, gh CLI in nix devshell, and usage documentation in METRICS.md.

rkuris

All my changes are just nits, feel free to use or ignore them and get this merged.

justfile

rkuris · 2026-01-27T17:23:25Z

justfile

+    echo "https://github.com/ava-labs/firewood/actions/runs/$run_id"
+    echo ""
+
+    $GH run watch "$run_id"


Is it better to use this or watch it on the web? Maybe we shouldn't run this and let them choose.

Since the script already resolves and wraps the gh CLI (falling back to nix if needed), waiting by default keeps the experience consistent for users who have the tooling set up. The URL is printed before the watch starts, so users can open it in their browser and Ctrl+C to exit if they prefer the web UI.

firewood/justfile

Line 190 in 12e170b

# Resolve gh CLI

Does that work for you, or would you prefer adding a something like no-wait flag?

Co-authored-by: Ron Kuris <ron.kuris@avalabs.org> Signed-off-by: Elvis <43846394+Elvis339@users.noreply.github.com>

## Why Track C-Chain reexecution benchmark performance over time. Catch regressions before production. Closes #1494 ## How Firewood → triggers AvalancheGo benchmark → downloads results → publishes to GitHub Pages <img width="746" height="509" alt="Screenshot 2026-01-27 at 16 12 02" src="https://github.com/user-attachments/assets/ff372ef3-67b8-450e-8874-5289517130c8" /> ## Changes - `scripts/bench-cchain-reexecution.sh` - Trigger AvalancheGo's C-Chain reexecution benchmark - Poll for workflow registration - Wait for completion and download artifacts - `.github/workflows/track-performance.yml` - Orchestrate benchmark trigger via the script - Publish results to GitHub Pages (main → `bench/`, branches → `dev/bench/{branch}/`) ## Usage ``` # Auth nix run ./ffi#gh -- auth login export GH_TOKEN=$(nix run ./ffi#gh -- auth token) # Predefined test ./scripts/bench-cchain-reexecution.sh trigger firewood-101-250k # With specific Firewood version FIREWOOD_REF=v0.0.18 ./scripts/bench-cchain-reexecution.sh trigger firewood-101-250k # Custom block range RUNNER=avalanche-avalanchego-runner-2ti \ FIREWOOD_REF=v0.0.18 \ CONFIG=firewood \ START_BLOCK=1 \ END_BLOCK=100 \ BLOCK_DIR_SRC=cchain-mainnet-blocks-200-ldb \ ./scripts/bench-cchain-reexecution.sh trigger # Other commands ./scripts/bench-cchain-reexecution.sh tests # list available tests ./scripts/bench-cchain-reexecution.sh list # list recent runs ./scripts/bench-cchain-reexecution.sh status <run_id> ``` - Set `FIREWOOD_REF=v0.0.18` explicitly. Without it, the workflow builds from `HEAD`, which currently fails due to changes in FFI layer ### Related AvalancheGo: ava-labs/avalanchego#4650 Local iteration PR: #1642 Followup: #1639 --------- Signed-off-by: Elvis <43846394+Elvis339@users.noreply.github.com> Co-authored-by: rodrigo <77309055+RodrigoVillar@users.noreply.github.com> Co-authored-by: Ron Kuris <ron.kuris@avalabs.org>

RodrigoVillar · 2026-01-29T14:34:30Z

METRICS.md

+just bench-cchain firewood-101-250k
+
+# With specific Firewood version
+FIREWOOD_REF=v0.1.0 just bench-cchain firewood-33m-40m


I believe you mentioned that just supports named parameters. If so, could you please used named parameters wherever possible?

RodrigoVillar · 2026-01-29T14:38:44Z

METRICS.md

+| Variable | Default | Description |
+|----------|---------|-------------|
+| `FIREWOOD_REF` | current commit | Firewood commit/tag/branch to build |
+| `AVALANCHEGO_REF` | master | AvalancheGo ref to test against |
+| `LIBEVM_REF` | - | Optional libevm ref |
+| `RUNNER` | avalanche-avalanchego-runner-2ti | GitHub Actions runner |
+| `TIMEOUT_MINUTES` | - | Workflow timeout |
+| `DOWNLOAD_DIR` | ./results | Directory for downloaded artifacts |
+
+**Custom mode variables** (when no test specified):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CONFIG` | firewood | VM config (firewood, hashdb, etc.) |
+| `START_BLOCK` | required | First block number |
+| `END_BLOCK` | required | Last block number |
+| `BLOCK_DIR_SRC` | required | S3 block directory |
+| `CURRENT_STATE_DIR_SRC` | - | S3 state directory (empty = genesis run) |


Given that this is a repetition of:

firewood/scripts/bench-cchain-reexecution.sh

Lines 16 to 31 in 06c4d0a

# ENVIRONMENT

# GH_TOKEN GitHub token for API access (required)

# TEST Predefined test name, alternative to arg (optional)

# FIREWOOD_REF Firewood commit/tag/branch, empty = AvalancheGo's go.mod default (optional)

# AVALANCHEGO_REF AvalancheGo ref to test against (default: master)

# RUNNER GitHub Actions runner label (default: avalanche-avalanchego-runner-2ti)

# LIBEVM_REF libevm ref (optional)

# TIMEOUT_MINUTES Workflow timeout in minutes (optional)

# DOWNLOAD_DIR Directory for downloaded artifacts (default: ./results)

#

# Custom mode (when no TEST/test arg specified):

# CONFIG VM config (default: firewood)

# START_BLOCK First block number (required)

# END_BLOCK Last block number (required)

# BLOCK_DIR_SRC S3 block directory, e.g., cchain-mainnet-blocks-200-ldb (required)

# CURRENT_STATE_DIR_SRC S3 state directory, empty = genesis run (optional)

Would it make sense to just tell clients to look at the documentation in scripts/bench-cchain-reexecution.sh for all possible options?

RodrigoVillar · 2026-01-29T14:42:14Z

METRICS.md

One of the requirements of adding GAB to Firewood was that developers would be able to create a branch from main, push a commit, and run GAB against their new branch. From this though, it's not evident that it's supported and that there's no documentation for this common workflow. Could we add a section walking through what running benchmarks against a branch would look like?

chore(track-performance): add bench-cchain just recipe and documentation

4151bb8

Add local developer tooling for triggering C-Chain reexecution benchmarks. Includes just recipe, gh CLI in nix devshell, and usage documentation in METRICS.md.

Elvis339 self-assigned this Jan 26, 2026

Elvis339 requested review from RodrigoVillar, alarso16, demosdemon and rkuris as code owners January 26, 2026 18:06

Elvis339 added DO NOT MERGE This PR is not meant to be merged in its current state testing c-chain labels Jan 26, 2026

Elvis339 mentioned this pull request Jan 26, 2026

ci(perf): Track Firewood Performance via AvalancheGo Benchmarks #1493

Merged

docs

12e170b

rkuris approved these changes Jan 27, 2026

View reviewed changes

Apply suggestions from code review

208a07c

Co-authored-by: Ron Kuris <ron.kuris@avalabs.org> Signed-off-by: Elvis <43846394+Elvis339@users.noreply.github.com>

RodrigoVillar mentioned this pull request Jan 28, 2026

ci: add scheduled benchmark runs (#1639) #1645

Open

3 tasks

RodrigoVillar requested changes Jan 29, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(track-performance): local iteration #1642

chore(track-performance): local iteration #1642

Uh oh!

Elvis339 commented Jan 26, 2026

Uh oh!

rkuris left a comment

Uh oh!

Uh oh!

Uh oh!

rkuris Jan 27, 2026

Uh oh!

Elvis339 Jan 27, 2026

Uh oh!

RodrigoVillar Jan 29, 2026

Uh oh!

RodrigoVillar Jan 29, 2026

Uh oh!

RodrigoVillar Jan 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

	# ENVIRONMENT
	# GH_TOKEN GitHub token for API access (required)
	# TEST Predefined test name, alternative to arg (optional)
	# FIREWOOD_REF Firewood commit/tag/branch, empty = AvalancheGo's go.mod default (optional)
	# AVALANCHEGO_REF AvalancheGo ref to test against (default: master)
	# RUNNER GitHub Actions runner label (default: avalanche-avalanchego-runner-2ti)
	# LIBEVM_REF libevm ref (optional)
	# TIMEOUT_MINUTES Workflow timeout in minutes (optional)
	# DOWNLOAD_DIR Directory for downloaded artifacts (default: ./results)
	#
	# Custom mode (when no TEST/test arg specified):
	# CONFIG VM config (default: firewood)
	# START_BLOCK First block number (required)
	# END_BLOCK Last block number (required)
	# BLOCK_DIR_SRC S3 block directory, e.g., cchain-mainnet-blocks-200-ldb (required)
	# CURRENT_STATE_DIR_SRC S3 state directory, empty = genesis run (optional)

chore(track-performance): local iteration #1642

Are you sure you want to change the base?

chore(track-performance): local iteration #1642

Uh oh!

Conversation

Elvis339 commented Jan 26, 2026

Why this should be merged

How this works

How this was tested

Uh oh!

rkuris left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

rkuris Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

Elvis339 Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

RodrigoVillar Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

RodrigoVillar Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

RodrigoVillar Jan 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants